home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / PInterfaces / DeviceNotify.p < prev    next >
Text File  |  1996-05-01  |  9KB  |  250 lines
  1. {
  2.      File:        DeviceNotify.p
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    Technology:    xxx put the technology version here xxx
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT DeviceNotify;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __DEVICENOTIFY__}
  28. {$SETC __DEVICENOTIFY__ := 1}
  29.  
  30. {$I+}
  31. {$SETC DeviceNotifyIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __KERNEL__}
  38. {$I Kernel.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __NAMEREGISTRY__}
  41. {$I NameRegistry.p}
  42. {$ENDC}
  43.  
  44. {$PUSH}
  45. {$ALIGN MAC68K}
  46. {$LibExport+}
  47.  
  48. {$IFC FOR_SYSTEM8_PREEMPTIVE }
  49. {
  50.  ß
  51. ##############################################################################
  52.     
  53.     File Name: DeviceNotifyPriv.h
  54.     
  55.     Description:
  56.                             The device notification service is used by Copland Kernel band
  57.                     Low level family expert code to inform high level "consumers" about
  58.                 hot plugging/un-plugging of devices.
  59.                 
  60.                 The High level families or code modules running in priviledged mode 
  61.                 can subscribe to the service with the DevNRegisterInterestIn().
  62.                 LL Family notifies its consumers through the DevNNotifyThatThisChanged().
  63.     
  64. ##############################################################################
  65. ############################
  66.  Defines
  67. ############################
  68. }
  69.  
  70. TYPE
  71.     DevNRef                                = UInt32;
  72. {
  73.      a connection Reference Num for a particular subscription
  74.                                         a consumer subscription is identified by a unique
  75.                                          DevNSubRef. In order to cancel a consumer registration,
  76.                                         the DevNSubRef must be specified.
  77.                                     
  78.                                         a  Reference Num for a particular notification
  79.                                         A notification is identified by a unique DevNRef,
  80.                                         since a notification can go through couple of states, and 
  81.                                         it needs to be tracked with a unique identifier.
  82.                                     
  83. }
  84. {
  85.  ß
  86. ########################################################################
  87.     Known & valid Service Category definitions are defined in DFM.h
  88. ########################################################################
  89. }
  90.  
  91. CONST
  92.     kDevNAllServiceCategories    = $FFFFFFFF;                    {  an option to subscribe to ALL valid service catagories }
  93.  
  94.     kMaxNumServiceCategories    = 20;                            {  ***†should be in DFM.h *** }
  95.  
  96. {
  97.  ß
  98. ########################################################################
  99.  Event definition:
  100.     If kDevNSoftRequestMask is set in conjunction with an event value,
  101.     then a soft request is indicated, and the DevN will handle all the
  102.     drudgery associated with two-way transactions, etc.
  103.     (e.g. If (kDevNRemoved and kDevNSoftRequestMask) is received, it's 
  104.     a soft eject request)
  105.     If kDevNSoftRequestMask is NOT set, then it's a hard request
  106.      If the kDevNWarningMask is set, then it's an event warning that 
  107.     a given event is about to happen (and the consumer can't do a thing
  108.     about it). It will be followed later on by a gone hard event.
  109.     the kDevNWarningMask and the kDevNSoftRequestMask can NOT be set at
  110.     the same time.
  111. ########################################################################
  112. }
  113.  
  114. TYPE
  115.     DevNEventType                        = UInt32;
  116. {
  117.  pre-defined event mask
  118.  ß
  119.  definition of valid global event
  120.  (10/11/95) Events are now enum instead of masks
  121.  enum for "unsigned" values
  122. }
  123.  
  124. CONST
  125.     kDevNSoftRequestMask        = $80000000;                    {  bit indicating soft request }
  126.     kDevNWarningMask            = $40000000;                    {  bit indicating a warning request }
  127.     kDevNAdded                    = 0;                            {  New device/media/bus available }
  128.     kDevNRemoved                = 1;                            {  Existing device/media/bus now gone }
  129.     kDevNWakeup                    = 2;                            {  Plug-in sw state no longer needs synchronization }
  130.     kDevNSleep                    = 3;                            {  Ask to synchronize SOFTWARE state of plug-in }
  131.                                                                 {  ...used by PowerMgr, DriverReplacer, Soft Dev Eject }
  132.     kDevNBootComplete            = 4;                            {  used by motherboard expert to inform DFM boot complete }
  133.     kDevNIOInitComplete            = 5;                            {  I/O system initialize complete }
  134.     kDevNNumOfPredefinedEvtInUse = 6;
  135.     kDevNHighestEvtInUse        = 5;
  136.  
  137. {  enum for "signed" values }
  138.     kDevNSoftEject                = $80000001;                    {  (kDevNRemoved | kDevNSoftRequestMask) }
  139.  
  140. {
  141.  ß
  142. ########################################################################
  143.     Routine return value definition
  144. ########################################################################
  145. }
  146.  
  147. TYPE
  148.     DevNPermissionResponse                = UInt32;
  149. {  status returned by consumer to DevN }
  150.  
  151. CONST
  152.     kDevNPermissionGranted        = 0;                            {  consumer consented that instant removal of }
  153.                                                                 {  node is OK  }
  154.     kDevNPermissionDelayed        = 1;                            {  can not grant permission now, will inform producer through . }
  155.                                                                 {  DevN at a later time (ignored by the DevN if hard request)  }
  156.     kDevNPermissionDenied        = 2;                            {  do Not allow requested event to take place }
  157.                                                                 {     (ignored by the DevN if hard request) }
  158.     kDevNValidPermissionMasks    = 3;
  159.  
  160. {
  161. ########################################################################
  162.     Error code definition
  163. ########################################################################
  164. }
  165.     kDevNMErrorCodeBase            = 0;
  166.     kInvalidSC                    = 1;                            {  subscribe with invalid Service Category code }
  167.     kInvalidEvent                = 2;                            {  subscribe with invalid event mask (zero) }
  168.     kInvalidHandler                = 3;                            {  subscribe with NULL handler address }
  169.     kNoSuchRef                    = 4;                            {  Specified ID can not be found }
  170.     kRecordNotFound                = 5;                            {  while unregistering, can not find record in array }
  171.     kNotEnoughEventMask            = 6;                            {  not enough masks for DevNMCreateNewEvent call }
  172.     kDeleteInvalidMasks            = 7;                            {  attempt to DevNMDeleteNewEvent on invalid event masks }
  173.     kInvalidEventCount            = 8;                            {  invalid event count parameter being passed in }
  174.     kInvalidPermission            = 9;                            {  bad permission returned from consumer }
  175.     kTokenNotFound                = 10;                            {  sub record lookup list token not found }
  176.  
  177. {
  178. ########################################################################
  179.     Subroutine Prototype
  180. ########################################################################
  181.  no more handlers
  182. ######################                    
  183.  called by consumer
  184. ######################    
  185. }
  186. FUNCTION DevNRegisterInterestIn(myFamily: OSType; eventCount: ItemCount; VAR events: DevNEventType; adminMessageObj: ObjectID; VAR thisRegistration: DevNRef; parm: UNIV Ptr): OSStatus; C;
  187. FUNCTION DevNUnregisterInterest(thisID: DevNRef): OSStatus; C;
  188. FUNCTION DevNMCreateNewEvent(VAR result: DevNEventType): OSStatus; C;
  189. {
  190.  call to register family defined events.
  191.  itemCount specifies how many events are desired
  192.     (Only create one event at a time)
  193. }
  194. FUNCTION DevNMDeleteNewEvent(event: DevNEventType): OSStatus; C;
  195. {  de-register the given event }
  196. FUNCTION DevNDelayedDownwardNotify(notifyRef: DevNRef; subscriptionRef: DevNRef; permission: DevNPermissionResponse): OSStatus; C;
  197. {
  198.  must be called after an kDevNPermissionDelayed is returned to the DevN
  199.     for a notification response.
  200. ######################                    
  201.  called by producer
  202. ######################                    
  203. }
  204. FUNCTION DevNNotifyThatThisChanged(whichServiceCategory: OSType; whatHappened: DevNEventType; VAR whichDevice: RegEntryRef; adminMessageObj: ObjectID; VAR notRef: DevNRef; parm: UNIV Ptr): DevNPermissionResponse; C;
  205. FUNCTION DevNNotifyEvents(whatHappened: DevNEventType; VAR whichDevice: RegEntryRef; adminMessageObj: ObjectID; VAR notRef: DevNRef; parm: UNIV Ptr): DevNPermissionResponse; C;
  206. {
  207. #####################################
  208.  Notification Message definitions        
  209. #####################################
  210. }
  211.  
  212. TYPE
  213.     DevNMessagePtr = ^DevNMessage;
  214.     DevNMessage = RECORD
  215.         AdminMessageType:        UInt32;
  216.         subMessageType:            UInt32;
  217.         serviceCategory:        OSType;
  218.         event:                    DevNEventType;
  219.         device:                    RegEntryRefPtr;
  220.         parm:                    Ptr;
  221.         notRef:                    DevNRef;
  222.         returnPermission:        DevNPermissionResponse;
  223.     END;
  224.  
  225. {
  226. #########################################################
  227.     Device Notification sub-message types.    
  228.     (This is in the "subMessageType" field inside
  229.         The DevNMessage structure)
  230. #########################################################
  231. }
  232.  
  233. CONST
  234.     kDevNNotifyMsg                = $01;
  235.     kDevNNotifyCancel            = $02;
  236.     kDevNNotifyDelayedReply        = $03;
  237.     kNextUnusedMsg                = $04;
  238.  
  239. {$ENDC}
  240. {$ALIGN RESET}
  241. {$POP}
  242.  
  243. {$SETC UsingIncludes := DeviceNotifyIncludes}
  244.  
  245. {$ENDC} {__DEVICENOTIFY__}
  246.  
  247. {$IFC NOT UsingIncludes}
  248.  END.
  249. {$ENDC}
  250.